home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / lib / perl / 5.10.0 / IO / Compress / Zip.pm < prev   
Encoding:
Perl POD Document  |  2009-06-26  |  39.7 KB  |  1,585 lines
  1. package IO::Compress::Zip ;
  2.  
  3. use strict ;
  4. use warnings;
  5. use bytes;
  6.  
  7. use IO::Compress::Base::Common  2.008 qw(:Status createSelfTiedObject);
  8. use IO::Compress::RawDeflate 2.008 ;
  9. use IO::Compress::Adapter::Deflate 2.008 ;
  10. use IO::Compress::Adapter::Identity 2.008 ;
  11. use IO::Compress::Zlib::Extra 2.008 ;
  12. use IO::Compress::Zip::Constants 2.008 ;
  13.  
  14.  
  15. use Compress::Raw::Zlib  2.008 qw(crc32) ;
  16. BEGIN
  17. {
  18.     eval { require IO::Compress::Adapter::Bzip2 ; 
  19.            import  IO::Compress::Adapter::Bzip2 2.008 ; 
  20.            require IO::Compress::Bzip2 ; 
  21.            import  IO::Compress::Bzip2 2.008 ; 
  22.          } ;
  23. }
  24.  
  25.  
  26. require Exporter ;
  27.  
  28. our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $ZipError);
  29.  
  30. $VERSION = '2.008';
  31. $ZipError = '';
  32.  
  33. @ISA = qw(Exporter IO::Compress::RawDeflate);
  34. @EXPORT_OK = qw( $ZipError zip ) ;
  35. %EXPORT_TAGS = %IO::Compress::RawDeflate::DEFLATE_CONSTANTS ;
  36. push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
  37.  
  38. $EXPORT_TAGS{zip_method} = [qw( ZIP_CM_STORE ZIP_CM_DEFLATE ZIP_CM_BZIP2 )];
  39. push @{ $EXPORT_TAGS{all} }, @{ $EXPORT_TAGS{zip_method} };
  40.  
  41. Exporter::export_ok_tags('all');
  42.  
  43. sub new
  44. {
  45.     my $class = shift ;
  46.  
  47.     my $obj = createSelfTiedObject($class, \$ZipError);    
  48.     $obj->_create(undef, @_);
  49. }
  50.  
  51. sub zip
  52. {
  53.     my $obj = createSelfTiedObject(undef, \$ZipError);    
  54.     return $obj->_def(@_);
  55. }
  56.  
  57. sub mkComp
  58. {
  59.     my $self = shift ;
  60.     my $class = shift ;
  61.     my $got = shift ;
  62.  
  63.     my ($obj, $errstr, $errno) ;
  64.  
  65.     if (*$self->{ZipData}{Method} == ZIP_CM_STORE) {
  66.         ($obj, $errstr, $errno) = IO::Compress::Adapter::Identity::mkCompObject(
  67.                                                  $got->value('Level'),
  68.                                                  $got->value('Strategy')
  69.                                                  );
  70.     }
  71.     elsif (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
  72.         ($obj, $errstr, $errno) = IO::Compress::Adapter::Deflate::mkCompObject(
  73.                                                  $got->value('CRC32'),
  74.                                                  $got->value('Adler32'),
  75.                                                  $got->value('Level'),
  76.                                                  $got->value('Strategy')
  77.                                                  );
  78.     }
  79.     elsif (*$self->{ZipData}{Method} == ZIP_CM_BZIP2) {
  80.         ($obj, $errstr, $errno) = IO::Compress::Adapter::Bzip2::mkCompObject(
  81.                                                 $got->value('BlockSize100K'),
  82.                                                 $got->value('WorkFactor'),
  83.                                                 $got->value('Verbosity')
  84.                                                );
  85.         *$self->{ZipData}{CRC32} = crc32(undef);
  86.     }
  87.  
  88.     return $self->saveErrorString(undef, $errstr, $errno)
  89.        if ! defined $obj;
  90.  
  91.     if (! defined *$self->{ZipData}{StartOffset}) {
  92.         *$self->{ZipData}{StartOffset} = 0;
  93.         *$self->{ZipData}{Offset} = new U64 ;
  94.     }
  95.  
  96.     return $obj;    
  97. }
  98.  
  99. sub reset
  100. {
  101.     my $self = shift ;
  102.  
  103.     *$self->{Compress}->reset();
  104.     *$self->{ZipData}{CRC32} = Compress::Raw::Zlib::crc32('');
  105.  
  106.     return STATUS_OK;    
  107. }
  108.  
  109. sub filterUncompressed
  110. {
  111.     my $self = shift ;
  112.  
  113.     if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
  114.         *$self->{ZipData}{CRC32} = *$self->{Compress}->crc32();
  115.     }
  116.     else {
  117.         *$self->{ZipData}{CRC32} = crc32(${$_[0]}, *$self->{ZipData}{CRC32});
  118.  
  119.     }
  120. }
  121.  
  122. sub mkHeader
  123. {
  124.     my $self  = shift;
  125.     my $param = shift ;
  126.     
  127.     *$self->{ZipData}{StartOffset} = *$self->{ZipData}{Offset}->get32bit() ;
  128.  
  129.     my $filename = '';
  130.     $filename = $param->value('Name') || '';
  131.  
  132.     my $comment = '';
  133.     $comment = $param->value('Comment') || '';
  134.  
  135.     my $hdr = '';
  136.  
  137.     my $time = _unixToDosTime($param->value('Time'));
  138.  
  139.     my $extra = '';
  140.     my $ctlExtra = '';
  141.     my $empty = 0;
  142.     my $osCode = $param->value('OS_Code') ;
  143.     my $extFileAttr = 0 ;
  144.  
  145.     if (*$self->{ZipData}{Zip64}) {
  146.         $empty = 0xFFFF;
  147.  
  148.         my $x = '';
  149.         $x .= pack "V V", 0, 0 ; # uncompressedLength   
  150.         $x .= pack "V V", 0, 0 ; # compressedLength   
  151.         $x .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to local hdr
  152.         #$x .= pack "V  ", 0    ; # disk no
  153.  
  154.         $x = IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_ZIP64, $x);
  155.         $extra .= $x;
  156.         $ctlExtra .= $x;
  157.     }
  158.  
  159.     if (! $param->value('Minimal')) {
  160.         if (defined $param->value('exTime'))
  161.         {
  162.             $extra .= mkExtendedTime($param->value('MTime'), 
  163.                                     $param->value('ATime'), 
  164.                                     $param->value('CTime'));
  165.  
  166.             $ctlExtra .= mkExtendedTime($param->value('MTime'));
  167.         }
  168.  
  169.         if ( $param->value('UID') && $osCode == ZIP_OS_CODE_UNIX)
  170.         {
  171.             $extra    .= mkUnix2Extra( $param->value('UID'), $param->value('GID'));
  172.             $ctlExtra .= mkUnix2Extra();
  173.         }
  174.  
  175.         # TODO - this code assumes Unix.
  176.         #$extFileAttr = 0666 << 16 
  177.         #    if $osCode == ZIP_OS_CODE_UNIX ;
  178.  
  179.         $extFileAttr = $param->value('ExtAttr') 
  180.             if defined $param->value('ExtAttr') ;
  181.  
  182.         $extra .= $param->value('ExtraFieldLocal') 
  183.             if defined $param->value('ExtraFieldLocal');
  184.  
  185.         $ctlExtra .= $param->value('ExtraFieldCentral') 
  186.             if defined $param->value('ExtraFieldCentral');
  187.     }
  188.  
  189.     my $gpFlag = 0 ;    
  190.     $gpFlag |= ZIP_GP_FLAG_STREAMING_MASK
  191.         if *$self->{ZipData}{Stream} ;
  192.  
  193.     my $method = *$self->{ZipData}{Method} ;
  194.  
  195.     my $version = $ZIP_CM_MIN_VERSIONS{$method};
  196.     $version = ZIP64_MIN_VERSION
  197.         if ZIP64_MIN_VERSION > $version && *$self->{ZipData}{Zip64};
  198.     my $madeBy = ($param->value('OS_Code') << 8) + $version;
  199.     my $extract = $version;
  200.  
  201.     *$self->{ZipData}{Version} = $version;
  202.     *$self->{ZipData}{MadeBy} = $madeBy;
  203.  
  204.     my $ifa = 0;
  205.     $ifa |= ZIP_IFA_TEXT_MASK
  206.         if $param->value('TextFlag');
  207.  
  208.     $hdr .= pack "V", ZIP_LOCAL_HDR_SIG ; # signature
  209.     $hdr .= pack 'v', $extract   ; # extract Version & OS
  210.     $hdr .= pack 'v', $gpFlag    ; # general purpose flag (set streaming mode)
  211.     $hdr .= pack 'v', $method    ; # compression method (deflate)
  212.     $hdr .= pack 'V', $time      ; # last mod date/time
  213.     $hdr .= pack 'V', 0          ; # crc32               - 0 when streaming
  214.     $hdr .= pack 'V', $empty     ; # compressed length   - 0 when streaming
  215.     $hdr .= pack 'V', $empty     ; # uncompressed length - 0 when streaming
  216.     $hdr .= pack 'v', length $filename ; # filename length
  217.     $hdr .= pack 'v', length $extra ; # extra length
  218.     
  219.     $hdr .= $filename ;
  220.     $hdr .= $extra ;
  221.  
  222.  
  223.     my $ctl = '';
  224.  
  225.     $ctl .= pack "V", ZIP_CENTRAL_HDR_SIG ; # signature
  226.     $ctl .= pack 'v', $madeBy    ; # version made by
  227.     $ctl .= pack 'v', $extract   ; # extract Version
  228.     $ctl .= pack 'v', $gpFlag    ; # general purpose flag (streaming mode)
  229.     $ctl .= pack 'v', $method    ; # compression method (deflate)
  230.     $ctl .= pack 'V', $time      ; # last mod date/time
  231.     $ctl .= pack 'V', 0          ; # crc32
  232.     $ctl .= pack 'V', $empty     ; # compressed length
  233.     $ctl .= pack 'V', $empty     ; # uncompressed length
  234.     $ctl .= pack 'v', length $filename ; # filename length
  235.     $ctl .= pack 'v', length $ctlExtra ; # extra length
  236.     $ctl .= pack 'v', length $comment ;  # file comment length
  237.     $ctl .= pack 'v', 0          ; # disk number start 
  238.     $ctl .= pack 'v', $ifa       ; # internal file attributes
  239.     $ctl .= pack 'V', $extFileAttr   ; # external file attributes
  240.     if (! *$self->{ZipData}{Zip64}) {
  241.         $ctl .= pack 'V', *$self->{ZipData}{Offset}->get32bit()  ; # offset to local header
  242.     }
  243.     else {
  244.         $ctl .= pack 'V', $empty ; # offset to local header
  245.     }
  246.     
  247.     $ctl .= $filename ;
  248.     *$self->{ZipData}{StartOffset64} = 4 + length $ctl;
  249.     $ctl .= $ctlExtra ;
  250.     $ctl .= $comment ;
  251.  
  252.     *$self->{ZipData}{Offset}->add(length $hdr) ;
  253.  
  254.     *$self->{ZipData}{CentralHeader} = $ctl;
  255.  
  256.     return $hdr;
  257. }
  258.  
  259. sub mkTrailer
  260. {
  261.     my $self = shift ;
  262.  
  263.     my $crc32 ;
  264.     if (*$self->{ZipData}{Method} == ZIP_CM_DEFLATE) {
  265.         $crc32 = pack "V", *$self->{Compress}->crc32();
  266.     }
  267.     else {
  268.         $crc32 = pack "V", *$self->{ZipData}{CRC32};
  269.     }
  270.  
  271.     my $ctl = *$self->{ZipData}{CentralHeader} ;
  272.  
  273.     my $sizes ;
  274.     if (! *$self->{ZipData}{Zip64}) {
  275.         $sizes .= *$self->{CompSize}->getPacked_V32() ;   # Compressed size
  276.         $sizes .= *$self->{UnCompSize}->getPacked_V32() ; # Uncompressed size
  277.     }
  278.     else {
  279.         $sizes .= *$self->{CompSize}->getPacked_V64() ;   # Compressed size
  280.         $sizes .= *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
  281.     }
  282.  
  283.     my $data = $crc32 . $sizes ;
  284.  
  285.  
  286.     my $hdr = '';
  287.  
  288.     if (*$self->{ZipData}{Stream}) {
  289.         $hdr  = pack "V", ZIP_DATA_HDR_SIG ;                       # signature
  290.         $hdr .= $data ;
  291.     }
  292.     else {
  293.         $self->writeAt(*$self->{ZipData}{StartOffset} + 14, $data)
  294.             or return undef;
  295.     }
  296.  
  297.     if (! *$self->{ZipData}{Zip64})
  298.       { substr($ctl, 16, length $data) = $data }
  299.     else {
  300.         substr($ctl, 16, length $crc32) = $crc32 ;
  301.         my $s  = *$self->{UnCompSize}->getPacked_V64() ; # Uncompressed size
  302.            $s .= *$self->{CompSize}->getPacked_V64() ;   # Compressed size
  303.         substr($ctl, *$self->{ZipData}{StartOffset64}, length $s) = $s ;
  304.     }
  305.  
  306.     *$self->{ZipData}{Offset}->add(length($hdr));
  307.     *$self->{ZipData}{Offset}->add( *$self->{CompSize} );
  308.     push @{ *$self->{ZipData}{CentralDir} }, $ctl ;
  309.  
  310.     return $hdr;
  311. }
  312.  
  313. sub mkFinalTrailer
  314. {
  315.     my $self = shift ;
  316.  
  317.     my $comment = '';
  318.     $comment = *$self->{ZipData}{ZipComment} ;
  319.  
  320.     my $cd_offset = *$self->{ZipData}{Offset}->get32bit() ; # offset to start central dir
  321.  
  322.     my $entries = @{ *$self->{ZipData}{CentralDir} };
  323.     my $cd = join '', @{ *$self->{ZipData}{CentralDir} };
  324.     my $cd_len = length $cd ;
  325.  
  326.     my $z64e = '';
  327.  
  328.     if ( *$self->{ZipData}{Zip64} ) {
  329.  
  330.         my $v  = *$self->{ZipData}{Version} ;
  331.         my $mb = *$self->{ZipData}{MadeBy} ;
  332.         $z64e .= pack 'v', $v             ; # Version made by
  333.         $z64e .= pack 'v', $mb            ; # Version to extract
  334.         $z64e .= pack 'V', 0              ; # number of disk
  335.         $z64e .= pack 'V', 0              ; # number of disk with central dir
  336.         $z64e .= U64::pack_V64 $entries   ; # entries in central dir on this disk
  337.         $z64e .= U64::pack_V64 $entries   ; # entries in central dir
  338.         $z64e .= U64::pack_V64 $cd_len    ; # size of central dir
  339.         $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to start central dir
  340.  
  341.         $z64e  = pack("V", ZIP64_END_CENTRAL_REC_HDR_SIG) # signature
  342.               .  U64::pack_V64(length $z64e)
  343.               .  $z64e ;
  344.  
  345.         *$self->{ZipData}{Offset}->add(length $cd) ; 
  346.  
  347.         $z64e .= pack "V", ZIP64_END_CENTRAL_LOC_HDR_SIG; # signature
  348.         $z64e .= pack 'V', 0              ; # number of disk with central dir
  349.         $z64e .= *$self->{ZipData}{Offset}->getPacked_V64() ; # offset to end zip64 central dir
  350.         $z64e .= pack 'V', 1              ; # Total number of disks 
  351.  
  352.         # TODO - fix these when info-zip 3 is fixed.
  353.         #$cd_len = 
  354.         #$cd_offset = 
  355.         $entries = 0xFFFF ;
  356.     }
  357.  
  358.     my $ecd = '';
  359.     $ecd .= pack "V", ZIP_END_CENTRAL_HDR_SIG ; # signature
  360.     $ecd .= pack 'v', 0          ; # number of disk
  361.     $ecd .= pack 'v', 0          ; # number of disk with central dir
  362.     $ecd .= pack 'v', $entries   ; # entries in central dir on this disk
  363.     $ecd .= pack 'v', $entries   ; # entries in central dir
  364.     $ecd .= pack 'V', $cd_len    ; # size of central dir
  365.     $ecd .= pack 'V', $cd_offset ; # offset to start central dir
  366.     $ecd .= pack 'v', length $comment ; # zipfile comment length
  367.     $ecd .= $comment;
  368.  
  369.     return $cd . $z64e . $ecd ;
  370. }
  371.  
  372. sub ckParams
  373. {
  374.     my $self = shift ;
  375.     my $got = shift;
  376.     
  377.     $got->value('CRC32' => 1);
  378.  
  379.     if (! $got->parsed('Time') ) {
  380.         # Modification time defaults to now.
  381.         $got->value('Time' => time) ;
  382.     }
  383.  
  384.     if (! $got->parsed('exTime') ) {
  385.         my $timeRef = $got->value('exTime');
  386.         if ( defined $timeRef) {
  387.             return $self->saveErrorString(undef, "exTime not a 3-element array ref")   
  388.                 if ref $timeRef ne 'ARRAY' || @$timeRef != 3;
  389.         }
  390.  
  391.         $got->value("MTime", $timeRef->[1]);
  392.         $got->value("ATime", $timeRef->[0]);
  393.         $got->value("CTime", $timeRef->[2]);
  394.     }
  395.  
  396.     *$self->{ZipData}{Zip64} = $got->value('Zip64');
  397.     *$self->{ZipData}{Stream} = $got->value('Stream');
  398.  
  399.     return $self->saveErrorString(undef, "Zip64 only supported if Stream enabled")   
  400.         if  *$self->{ZipData}{Zip64} && ! *$self->{ZipData}{Stream} ;
  401.  
  402.     my $method = $got->value('Method');
  403.     return $self->saveErrorString(undef, "Unknown Method '$method'")   
  404.         if ! defined $ZIP_CM_MIN_VERSIONS{$method};
  405.  
  406.     return $self->saveErrorString(undef, "Bzip2 not available")
  407.         if $method == ZIP_CM_BZIP2 and 
  408.            ! defined $IO::Compress::Adapter::Bzip2::VERSION;
  409.  
  410.     *$self->{ZipData}{Method} = $method;
  411.  
  412.     *$self->{ZipData}{ZipComment} = $got->value('ZipComment') ;
  413.  
  414.     for my $name (qw( ExtraFieldLocal ExtraFieldCentral ))
  415.     {
  416.         my $data = $got->value($name) ;
  417.         if (defined $data) {
  418.             my $bad = IO::Compress::Zlib::Extra::parseExtraField($data, 1, 0) ;
  419.             return $self->saveErrorString(undef, "Error with $name Parameter: $bad")
  420.                 if $bad ;
  421.  
  422.             $got->value($name, $data) ;
  423.         }
  424.     }
  425.  
  426.     return undef
  427.         if defined $IO::Compress::Bzip2::VERSION
  428.             and ! IO::Compress::Bzip2::ckParams($self, $got);
  429.  
  430.     return 1 ;
  431. }
  432.  
  433. #sub newHeader
  434. #{
  435. #    my $self = shift ;
  436. #
  437. #    return $self->mkHeader(*$self->{Got});
  438. #}
  439.  
  440. sub getExtraParams
  441. {
  442.     my $self = shift ;
  443.  
  444.     use IO::Compress::Base::Common  2.008 qw(:Parse);
  445.     use Compress::Raw::Zlib  2.008 qw(Z_DEFLATED Z_DEFAULT_COMPRESSION Z_DEFAULT_STRATEGY);
  446.  
  447.     my @Bzip2 = ();
  448.     
  449.     @Bzip2 = IO::Compress::Bzip2::getExtraParams($self)
  450.         if defined $IO::Compress::Bzip2::VERSION;
  451.     
  452.     return (
  453.             # zlib behaviour
  454.             $self->getZlibParams(),
  455.  
  456.             'Stream'    => [1, 1, Parse_boolean,   1],
  457.            #'Store'     => [0, 1, Parse_boolean,   0],
  458.             'Method'    => [0, 1, Parse_unsigned,  ZIP_CM_DEFLATE],
  459.             
  460. #            # Zip header fields
  461.             'Minimal'   => [0, 1, Parse_boolean,   0],
  462.             'Zip64'     => [0, 1, Parse_boolean,   0],
  463.             'Comment'   => [0, 1, Parse_any,       ''],
  464.             'ZipComment'=> [0, 1, Parse_any,       ''],
  465.             'Name'      => [0, 1, Parse_any,       ''],
  466.             'Time'      => [0, 1, Parse_any,       undef],
  467.             'exTime'    => [0, 1, Parse_any,       undef],
  468.             'ExtAttr'   => [0, 1, Parse_any,       0],
  469.             'OS_Code'   => [0, 1, Parse_unsigned,  $Compress::Raw::Zlib::gzip_os_code],
  470.             
  471.            'TextFlag'  => [0, 1, Parse_boolean,   0],
  472.            'ExtraFieldLocal'  => [0, 1, Parse_any,    undef],
  473.            'ExtraFieldCentral'=> [0, 1, Parse_any,    undef],
  474.  
  475.             @Bzip2,
  476.         );
  477. }
  478.  
  479. sub getInverseClass
  480. {
  481.     return ('IO::Uncompress::Unzip',
  482.                 \$IO::Uncompress::Unzip::UnzipError);
  483. }
  484.  
  485. sub getFileInfo
  486. {
  487.     my $self = shift ;
  488.     my $params = shift;
  489.     my $filename = shift ;
  490.  
  491.     my ($mode, $uid, $gid, $atime, $mtime, $ctime) 
  492.                 = (stat($filename))[2, 4,5, 8,9,10] ;
  493.  
  494.     $params->value('Name' => $filename)
  495.         if ! $params->parsed('Name') ;
  496.  
  497.     $params->value('Time' => $mtime) 
  498.         if ! $params->parsed('Time') ;
  499.     
  500.     if ( ! $params->parsed('exTime'))
  501.     {
  502.         $params->value('MTime' => $mtime) ;
  503.         $params->value('ATime' => $atime) ;
  504.         $params->value('CTime' => undef) ; # No Creation time
  505.     }
  506.  
  507.     $params->value('ExtAttr' => $mode << 16) 
  508.         if ! $params->parsed('ExtAttr');
  509.  
  510.     $params->value('UID' => $uid) ;
  511.     $params->value('GID' => $gid) ;
  512.     
  513. }
  514.  
  515. sub mkExtendedTime
  516. {
  517.     # order expected is m, a, c
  518.  
  519.     my $times = '';
  520.     my $bit = 1 ;
  521.     my $flags = 0;
  522.  
  523.     for my $time (@_)
  524.     {
  525.         if (defined $time)
  526.         {
  527.             $flags |= $bit;
  528.             $times .= pack("V", $time);
  529.         }
  530.  
  531.         $bit <<= 1 ;
  532.     }
  533.  
  534.     return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_EXT_TIMESTAMP,
  535.                                                  pack("C", $flags) .  $times);
  536. }
  537.  
  538. sub mkUnix2Extra
  539. {
  540.     my $ids = '';
  541.     for my $id (@_)
  542.     {
  543.         $ids .= pack("v", $id);
  544.     }
  545.  
  546.     return IO::Compress::Zlib::Extra::mkSubField(ZIP_EXTRA_ID_INFO_ZIP_UNIX2, 
  547.                                                  $ids);
  548. }
  549.  
  550.  
  551. # from Archive::Zip
  552. sub _unixToDosTime    # Archive::Zip::Member
  553. {
  554.     my $time_t = shift;
  555.     # TODO - add something to cope with unix time < 1980 
  556.     my ( $sec, $min, $hour, $mday, $mon, $year ) = localtime($time_t);
  557.     my $dt = 0;
  558.     $dt += ( $sec >> 1 );
  559.     $dt += ( $min << 5 );
  560.     $dt += ( $hour << 11 );
  561.     $dt += ( $mday << 16 );
  562.     $dt += ( ( $mon + 1 ) << 21 );
  563.     $dt += ( ( $year - 80 ) << 25 );
  564.     return $dt;
  565. }
  566.  
  567. 1;
  568.  
  569. __END__
  570.  
  571. =head1 NAME
  572.  
  573.  
  574.  
  575. IO::Compress::Zip - Write zip files/buffers
  576.  
  577.  
  578.  
  579. =head1 SYNOPSIS
  580.  
  581.     use IO::Compress::Zip qw(zip $ZipError) ;
  582.  
  583.  
  584.     my $status = zip $input => $output [,OPTS] 
  585.         or die "zip failed: $ZipError\n";
  586.  
  587.     my $z = new IO::Compress::Zip $output [,OPTS]
  588.         or die "zip failed: $ZipError\n";
  589.  
  590.     $z->print($string);
  591.     $z->printf($format, $string);
  592.     $z->write($string);
  593.     $z->syswrite($string [, $length, $offset]);
  594.     $z->flush();
  595.     $z->tell();
  596.     $z->eof();
  597.     $z->seek($position, $whence);
  598.     $z->binmode();
  599.     $z->fileno();
  600.     $z->opened();
  601.     $z->autoflush();
  602.     $z->input_line_number();
  603.     $z->newStream( [OPTS] );
  604.     
  605.     $z->deflateParams();
  606.     
  607.     $z->close() ;
  608.  
  609.     $ZipError ;
  610.  
  611.     # IO::File mode
  612.  
  613.     print $z $string;
  614.     printf $z $format, $string;
  615.     tell $z
  616.     eof $z
  617.     seek $z, $position, $whence
  618.     binmode $z
  619.     fileno $z
  620.     close $z ;
  621.     
  622.  
  623. =head1 DESCRIPTION
  624.  
  625.  
  626. This module provides a Perl interface that allows writing zip 
  627. compressed data to files or buffer.
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637. The primary purpose of this module is to provide streaming write access to
  638. zip files and buffers. It is not a general-purpose file archiver. If that
  639. is what you want, check out C<Archive::Zip>.
  640.  
  641. At present three compression methods are supported by IO::Compress::Zip,
  642. namely Store (no compression at all), Deflate and Bzip2.
  643.  
  644. Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
  645. be installed.
  646.  
  647.  
  648.  
  649.  
  650. For reading zip files/buffers, see the companion module 
  651. L<IO::Uncompress::Unzip|IO::Uncompress::Unzip>.
  652.  
  653.  
  654. =head1 Functional Interface
  655.  
  656. A top-level function, C<zip>, is provided to carry out
  657. "one-shot" compression between buffers and/or files. For finer
  658. control over the compression process, see the L</"OO Interface">
  659. section.
  660.  
  661.     use IO::Compress::Zip qw(zip $ZipError) ;
  662.  
  663.     zip $input => $output [,OPTS] 
  664.         or die "zip failed: $ZipError\n";
  665.  
  666.  
  667.  
  668. The functional interface needs Perl5.005 or better.
  669.  
  670.  
  671. =head2 zip $input => $output [, OPTS]
  672.  
  673.  
  674. C<zip> expects at least two parameters, C<$input> and C<$output>.
  675.  
  676. =head3 The C<$input> parameter
  677.  
  678. The parameter, C<$input>, is used to define the source of
  679. the uncompressed data. 
  680.  
  681. It can take one of the following forms:
  682.  
  683. =over 5
  684.  
  685. =item A filename
  686.  
  687. If the C<$input> parameter is a simple scalar, it is assumed to be a
  688. filename. This file will be opened for reading and the input data
  689. will be read from it.
  690.  
  691. =item A filehandle
  692.  
  693. If the C<$input> parameter is a filehandle, the input data will be
  694. read from it.
  695. The string '-' can be used as an alias for standard input.
  696.  
  697. =item A scalar reference 
  698.  
  699. If C<$input> is a scalar reference, the input data will be read
  700. from C<$$input>.
  701.  
  702. =item An array reference 
  703.  
  704. If C<$input> is an array reference, each element in the array must be a
  705. filename.
  706.  
  707. The input data will be read from each file in turn. 
  708.  
  709. The complete array will be walked to ensure that it only
  710. contains valid filenames before any data is compressed.
  711.  
  712.  
  713.  
  714. =item An Input FileGlob string
  715.  
  716. If C<$input> is a string that is delimited by the characters "<" and ">"
  717. C<zip> will assume that it is an I<input fileglob string>. The
  718. input is the list of files that match the fileglob.
  719.  
  720. If the fileglob does not match any files ...
  721.  
  722. See L<File::GlobMapper|File::GlobMapper> for more details.
  723.  
  724.  
  725. =back
  726.  
  727. If the C<$input> parameter is any other type, C<undef> will be returned.
  728.  
  729.  
  730. In addition, if C<$input> is a simple filename, the default values for
  731. the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options will be sourced from that file.
  732.  
  733. If you do not want to use these defaults they can be overridden by
  734. explicitly setting the C<Name>, C<Time>, C<ExtAttr> and C<exTime> options or by setting the
  735. C<Minimal> parameter.
  736.  
  737.  
  738.  
  739. =head3 The C<$output> parameter
  740.  
  741. The parameter C<$output> is used to control the destination of the
  742. compressed data. This parameter can take one of these forms.
  743.  
  744. =over 5
  745.  
  746. =item A filename
  747.  
  748. If the C<$output> parameter is a simple scalar, it is assumed to be a
  749. filename.  This file will be opened for writing and the compressed
  750. data will be written to it.
  751.  
  752. =item A filehandle
  753.  
  754. If the C<$output> parameter is a filehandle, the compressed data
  755. will be written to it.
  756. The string '-' can be used as an alias for standard output.
  757.  
  758.  
  759. =item A scalar reference 
  760.  
  761. If C<$output> is a scalar reference, the compressed data will be
  762. stored in C<$$output>.
  763.  
  764.  
  765.  
  766. =item An Array Reference
  767.  
  768. If C<$output> is an array reference, the compressed data will be
  769. pushed onto the array.
  770.  
  771. =item An Output FileGlob
  772.  
  773. If C<$output> is a string that is delimited by the characters "<" and ">"
  774. C<zip> will assume that it is an I<output fileglob string>. The
  775. output is the list of files that match the fileglob.
  776.  
  777. When C<$output> is an fileglob string, C<$input> must also be a fileglob
  778. string. Anything else is an error.
  779.  
  780. =back
  781.  
  782. If the C<$output> parameter is any other type, C<undef> will be returned.
  783.  
  784.  
  785.  
  786. =head2 Notes
  787.  
  788.  
  789.  
  790. When C<$input> maps to multiple files/buffers and C<$output> is a single
  791. file/buffer the input files/buffers will each be stored
  792. in C<$output> as a distinct entry.
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799. =head2 Optional Parameters
  800.  
  801. Unless specified below, the optional parameters for C<zip>,
  802. C<OPTS>, are the same as those used with the OO interface defined in the
  803. L</"Constructor Options"> section below.
  804.  
  805. =over 5
  806.  
  807. =item C<< AutoClose => 0|1 >>
  808.  
  809. This option applies to any input or output data streams to 
  810. C<zip> that are filehandles.
  811.  
  812. If C<AutoClose> is specified, and the value is true, it will result in all
  813. input and/or output filehandles being closed once C<zip> has
  814. completed.
  815.  
  816. This parameter defaults to 0.
  817.  
  818.  
  819. =item C<< BinModeIn => 0|1 >>
  820.  
  821. When reading from a file or filehandle, set C<binmode> before reading.
  822.  
  823. Defaults to 0.
  824.  
  825.  
  826.  
  827.  
  828.  
  829. =item C<< Append => 0|1 >>
  830.  
  831. TODO
  832.  
  833.  
  834.  
  835. =back
  836.  
  837.  
  838.  
  839. =head2 Examples
  840.  
  841. To read the contents of the file C<file1.txt> and write the compressed
  842. data to the file C<file1.txt.zip>.
  843.  
  844.     use strict ;
  845.     use warnings ;
  846.     use IO::Compress::Zip qw(zip $ZipError) ;
  847.  
  848.     my $input = "file1.txt";
  849.     zip $input => "$input.zip"
  850.         or die "zip failed: $ZipError\n";
  851.  
  852.  
  853. To read from an existing Perl filehandle, C<$input>, and write the
  854. compressed data to a buffer, C<$buffer>.
  855.  
  856.     use strict ;
  857.     use warnings ;
  858.     use IO::Compress::Zip qw(zip $ZipError) ;
  859.     use IO::File ;
  860.  
  861.     my $input = new IO::File "<file1.txt"
  862.         or die "Cannot open 'file1.txt': $!\n" ;
  863.     my $buffer ;
  864.     zip $input => \$buffer 
  865.         or die "zip failed: $ZipError\n";
  866.  
  867. To compress all files in the directory "/my/home" that match "*.txt"
  868. and store the compressed data in the same directory
  869.  
  870.     use strict ;
  871.     use warnings ;
  872.     use IO::Compress::Zip qw(zip $ZipError) ;
  873.  
  874.     zip '</my/home/*.txt>' => '<*.zip>'
  875.         or die "zip failed: $ZipError\n";
  876.  
  877. and if you want to compress each file one at a time, this will do the trick
  878.  
  879.     use strict ;
  880.     use warnings ;
  881.     use IO::Compress::Zip qw(zip $ZipError) ;
  882.  
  883.     for my $input ( glob "/my/home/*.txt" )
  884.     {
  885.         my $output = "$input.zip" ;
  886.         zip $input => $output 
  887.             or die "Error compressing '$input': $ZipError\n";
  888.     }
  889.  
  890.  
  891. =head1 OO Interface
  892.  
  893. =head2 Constructor
  894.  
  895. The format of the constructor for C<IO::Compress::Zip> is shown below
  896.  
  897.     my $z = new IO::Compress::Zip $output [,OPTS]
  898.         or die "IO::Compress::Zip failed: $ZipError\n";
  899.  
  900. It returns an C<IO::Compress::Zip> object on success and undef on failure. 
  901. The variable C<$ZipError> will contain an error message on failure.
  902.  
  903. If you are running Perl 5.005 or better the object, C<$z>, returned from 
  904. IO::Compress::Zip can be used exactly like an L<IO::File|IO::File> filehandle. 
  905. This means that all normal output file operations can be carried out 
  906. with C<$z>. 
  907. For example, to write to a compressed file/buffer you can use either of 
  908. these forms
  909.  
  910.     $z->print("hello world\n");
  911.     print $z "hello world\n";
  912.  
  913. The mandatory parameter C<$output> is used to control the destination
  914. of the compressed data. This parameter can take one of these forms.
  915.  
  916. =over 5
  917.  
  918. =item A filename
  919.  
  920. If the C<$output> parameter is a simple scalar, it is assumed to be a
  921. filename. This file will be opened for writing and the compressed data
  922. will be written to it.
  923.  
  924. =item A filehandle
  925.  
  926. If the C<$output> parameter is a filehandle, the compressed data will be
  927. written to it.
  928. The string '-' can be used as an alias for standard output.
  929.  
  930.  
  931. =item A scalar reference 
  932.  
  933. If C<$output> is a scalar reference, the compressed data will be stored
  934. in C<$$output>.
  935.  
  936. =back
  937.  
  938. If the C<$output> parameter is any other type, C<IO::Compress::Zip>::new will
  939. return undef.
  940.  
  941. =head2 Constructor Options
  942.  
  943. C<OPTS> is any combination of the following options:
  944.  
  945. =over 5
  946.  
  947. =item C<< AutoClose => 0|1 >>
  948.  
  949. This option is only valid when the C<$output> parameter is a filehandle. If
  950. specified, and the value is true, it will result in the C<$output> being
  951. closed once either the C<close> method is called or the C<IO::Compress::Zip>
  952. object is destroyed.
  953.  
  954. This parameter defaults to 0.
  955.  
  956. =item C<< Append => 0|1 >>
  957.  
  958. Opens C<$output> in append mode. 
  959.  
  960. The behaviour of this option is dependent on the type of C<$output>.
  961.  
  962. =over 5
  963.  
  964. =item * A Buffer
  965.  
  966. If C<$output> is a buffer and C<Append> is enabled, all compressed data
  967. will be append to the end if C<$output>. Otherwise C<$output> will be
  968. cleared before any data is written to it.
  969.  
  970. =item * A Filename
  971.  
  972. If C<$output> is a filename and C<Append> is enabled, the file will be
  973. opened in append mode. Otherwise the contents of the file, if any, will be
  974. truncated before any compressed data is written to it.
  975.  
  976. =item * A Filehandle
  977.  
  978. If C<$output> is a filehandle, the file pointer will be positioned to the
  979. end of the file via a call to C<seek> before any compressed data is written
  980. to it.  Otherwise the file pointer will not be moved.
  981.  
  982. =back
  983.  
  984. This parameter defaults to 0.
  985.  
  986.  
  987.  
  988. =item C<< Name => $string >>
  989.  
  990. Stores the contents of C<$string> in the zip filename header field. If
  991. C<Name> is not specified, no zip filename field will be created.
  992.  
  993. =item C<< Time => $number >>
  994.  
  995. Sets the last modified time field in the zip header to $number.
  996.  
  997. This field defaults to the time the C<IO::Compress::Zip> object was created
  998. if this option is not specified.
  999.  
  1000. =item C<< ExtAttr => $attr >>
  1001.  
  1002. This option controls the "external file attributes" field in the central
  1003. header of the zip file. This is a 4 byte field.
  1004.  
  1005. This option defaults to 0.
  1006.  
  1007. =item C<< exTime => [$atime, $mtime, $ctime] >>
  1008.  
  1009. This option expects an array reference with exactly three elements:
  1010. C<$atime>, C<mtime> and C<$ctime>. These correspond to the last access
  1011. time, last modification time and creation time respectively.
  1012.  
  1013. It uses these values to set the extended timestamp field in the local zip
  1014. header to the three values, $atime, $mtime, $ctime and sets the extended
  1015. timestamp field in the central zip header to C<$mtime>.
  1016.  
  1017. If any of the three values is C<undef> that time value will not be used.
  1018. So, for example, to set only the C<$mtime> you would use this
  1019.  
  1020.     exTime => [undef, $mtime, undef]
  1021.  
  1022. If the C<Minimal> option is set to true, this option will be ignored.
  1023.  
  1024. By default no extended time field is created.
  1025.  
  1026. =item C<< Comment => $comment >>
  1027.  
  1028. Stores the contents of C<$comment> in the Central File Header of
  1029. the zip file.
  1030.  
  1031. By default, no comment field is written to the zip file.
  1032.  
  1033. =item C<< ZipComment => $comment >>
  1034.  
  1035. Stores the contents of C<$comment> in the End of Central Directory record
  1036. of the zip file.
  1037.  
  1038. By default, no comment field is written to the zip file.
  1039.  
  1040. =item C<< Method => $method >>
  1041.  
  1042. Controls which compression method is used. At present three compression
  1043. methods are supported, namely Store (no compression at all), Deflate and
  1044. Bzip2.
  1045.  
  1046. The symbols, ZIP_CM_STORE, ZIP_CM_DEFLATE and ZIP_CM_BZIP2 are used to
  1047. select the compression method.
  1048.  
  1049. These constants are not imported by C<IO::Compress::Zip> by default.
  1050.  
  1051.     use IO::Compress::Zip qw(:zip_method);
  1052.     use IO::Compress::Zip qw(:constants);
  1053.     use IO::Compress::Zip qw(:all);
  1054.  
  1055. Note that to create Bzip2 content, the module C<IO::Compress::Bzip2> must
  1056. be installed. A fatal error will be thrown if you attempt to create Bzip2
  1057. content when C<IO::Compress::Bzip2> is not available.
  1058.  
  1059. The default method is ZIP_CM_DEFLATE.
  1060.  
  1061. =item C<< Stream => 0|1 >>
  1062.  
  1063. This option controls whether the zip file/buffer output is created in
  1064. streaming mode.
  1065.  
  1066. Note that when outputting to a file with streaming mode disabled (C<Stream>
  1067. is 0), the output file must be seekable.
  1068.  
  1069. The default is 1.
  1070.  
  1071. =item C<< Zip64 => 0|1 >>
  1072.  
  1073. Create a Zip64 zip file/buffer. This option should only be used if you want
  1074. to store files larger than 4 Gig.
  1075.  
  1076. If you intend to manipulate the Zip64 zip files created with this module
  1077. using an external zip/unzip make sure that it supports streaming Zip64.  
  1078.  
  1079. In particular, if you are using Info-Zip you need to have zip version 3.x
  1080. or better to update a Zip64 archive and unzip version 6.x to read a zip64
  1081. archive. At the time of writing both are beta status.
  1082.  
  1083. When the C<Zip64> option is enabled, the C<Stream> option I<must> be
  1084. enabled as well.
  1085.  
  1086. The default is 0.
  1087.  
  1088. =item C<< TextFlag => 0|1 >>
  1089.  
  1090. This parameter controls the setting of a bit in the zip central header. It
  1091. is used to signal that the data stored in the zip file/buffer is probably
  1092. text.
  1093.  
  1094. The default is 0. 
  1095.  
  1096. =item C<< ExtraFieldLocal => $data >>
  1097. =item C<< ExtraFieldCentral => $data >>
  1098.  
  1099. These options allows additional metadata to be stored in the local and
  1100. central headers in the zip file/buffer.
  1101.  
  1102. An extra field consists of zero or more subfields. Each subfield consists
  1103. of a two byte header followed by the subfield data.
  1104.  
  1105. The list of subfields can be supplied in any of the following formats
  1106.  
  1107.     ExtraFieldLocal => [$id1, $data1,
  1108.                         $id2, $data2,
  1109.                          ...
  1110.                        ]
  1111.  
  1112.     ExtraFieldLocal => [ [$id1 => $data1],
  1113.                          [$id2 => $data2],
  1114.                          ...
  1115.                        ]
  1116.  
  1117.     ExtraFieldLocal => { $id1 => $data1,
  1118.                          $id2 => $data2,
  1119.                          ...
  1120.                        }
  1121.  
  1122. Where C<$id1>, C<$id2> are two byte subfield ID's. 
  1123.  
  1124. If you use the hash syntax, you have no control over the order in which
  1125. the ExtraSubFields are stored, plus you cannot have SubFields with
  1126. duplicate ID.
  1127.  
  1128. Alternatively the list of subfields can by supplied as a scalar, thus
  1129.  
  1130.     ExtraField => $rawdata
  1131.  
  1132. The Extended Time field, set using the C<exTime> option, is an example of
  1133. an extended field.
  1134.  
  1135.  
  1136.  
  1137. If the C<Minimal> option is set to true, this option will be ignored.
  1138.  
  1139. The maximum size of an extra field 65535 bytes.
  1140.  
  1141. =item C<< Minimal => 1|0 >>
  1142.  
  1143. If specified, this option will disable the creation of all extended fields
  1144. in the zip local and central headers. So the C<exTime>, C<ExtraFieldLocal>
  1145. and C<ExtraFieldCentral> options will be ignored.
  1146.  
  1147. This parameter defaults to 0.
  1148.  
  1149. =item C<< BlockSize100K => number >>
  1150.  
  1151. Specify the number of 100K blocks bzip2 uses during compression. 
  1152.  
  1153. Valid values are from 1 to 9, where 9 is best compression.
  1154.  
  1155. This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
  1156. otherwise.
  1157.  
  1158. The default is 1.
  1159.  
  1160. =item C<< WorkFactor => number >>
  1161.  
  1162. Specifies how much effort bzip2 should take before resorting to a slower
  1163. fallback compression algorithm.
  1164.  
  1165. Valid values range from 0 to 250, where 0 means use the default value 30.
  1166.  
  1167. This option is only valid if the C<Method> is ZIP_CM_BZIP2. It is ignored
  1168. otherwise.
  1169.  
  1170. The default is 0.
  1171.  
  1172.  
  1173.  
  1174.  
  1175. =item -Level 
  1176.  
  1177. Defines the compression level used by zlib. The value should either be
  1178. a number between 0 and 9 (0 means no compression and 9 is maximum
  1179. compression), or one of the symbolic constants defined below.
  1180.  
  1181.    Z_NO_COMPRESSION
  1182.    Z_BEST_SPEED
  1183.    Z_BEST_COMPRESSION
  1184.    Z_DEFAULT_COMPRESSION
  1185.  
  1186. The default is Z_DEFAULT_COMPRESSION.
  1187.  
  1188. Note, these constants are not imported by C<IO::Compress::Zip> by default.
  1189.  
  1190.     use IO::Compress::Zip qw(:strategy);
  1191.     use IO::Compress::Zip qw(:constants);
  1192.     use IO::Compress::Zip qw(:all);
  1193.  
  1194. =item -Strategy 
  1195.  
  1196. Defines the strategy used to tune the compression. Use one of the symbolic
  1197. constants defined below.
  1198.  
  1199.    Z_FILTERED
  1200.    Z_HUFFMAN_ONLY
  1201.    Z_RLE
  1202.    Z_FIXED
  1203.    Z_DEFAULT_STRATEGY
  1204.  
  1205. The default is Z_DEFAULT_STRATEGY.
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212. =item C<< Strict => 0|1 >>
  1213.  
  1214.  
  1215.  
  1216. This is a placeholder option.
  1217.  
  1218.  
  1219.  
  1220. =back
  1221.  
  1222. =head2 Examples
  1223.  
  1224. TODO
  1225.  
  1226. =head1 Methods 
  1227.  
  1228. =head2 print
  1229.  
  1230. Usage is
  1231.  
  1232.     $z->print($data)
  1233.     print $z $data
  1234.  
  1235. Compresses and outputs the contents of the C<$data> parameter. This
  1236. has the same behaviour as the C<print> built-in.
  1237.  
  1238. Returns true if successful.
  1239.  
  1240. =head2 printf
  1241.  
  1242. Usage is
  1243.  
  1244.     $z->printf($format, $data)
  1245.     printf $z $format, $data
  1246.  
  1247. Compresses and outputs the contents of the C<$data> parameter.
  1248.  
  1249. Returns true if successful.
  1250.  
  1251. =head2 syswrite
  1252.  
  1253. Usage is
  1254.  
  1255.     $z->syswrite $data
  1256.     $z->syswrite $data, $length
  1257.     $z->syswrite $data, $length, $offset
  1258.  
  1259. Compresses and outputs the contents of the C<$data> parameter.
  1260.  
  1261. Returns the number of uncompressed bytes written, or C<undef> if
  1262. unsuccessful.
  1263.  
  1264. =head2 write
  1265.  
  1266. Usage is
  1267.  
  1268.     $z->write $data
  1269.     $z->write $data, $length
  1270.     $z->write $data, $length, $offset
  1271.  
  1272. Compresses and outputs the contents of the C<$data> parameter.
  1273.  
  1274. Returns the number of uncompressed bytes written, or C<undef> if
  1275. unsuccessful.
  1276.  
  1277. =head2 flush
  1278.  
  1279. Usage is
  1280.  
  1281.  
  1282.     $z->flush;
  1283.     $z->flush($flush_type);
  1284.  
  1285.  
  1286. Flushes any pending compressed data to the output file/buffer.
  1287.  
  1288.  
  1289. This method takes an optional parameter, C<$flush_type>, that controls
  1290. how the flushing will be carried out. By default the C<$flush_type>
  1291. used is C<Z_FINISH>. Other valid values for C<$flush_type> are
  1292. C<Z_NO_FLUSH>, C<Z_SYNC_FLUSH>, C<Z_FULL_FLUSH> and C<Z_BLOCK>. It is
  1293. strongly recommended that you only set the C<flush_type> parameter if
  1294. you fully understand the implications of what it does - overuse of C<flush>
  1295. can seriously degrade the level of compression achieved. See the C<zlib>
  1296. documentation for details.
  1297.  
  1298.  
  1299. Returns true on success.
  1300.  
  1301.  
  1302. =head2 tell
  1303.  
  1304. Usage is
  1305.  
  1306.     $z->tell()
  1307.     tell $z
  1308.  
  1309. Returns the uncompressed file offset.
  1310.  
  1311. =head2 eof
  1312.  
  1313. Usage is
  1314.  
  1315.     $z->eof();
  1316.     eof($z);
  1317.  
  1318.  
  1319.  
  1320. Returns true if the C<close> method has been called.
  1321.  
  1322.  
  1323.  
  1324. =head2 seek
  1325.  
  1326.     $z->seek($position, $whence);
  1327.     seek($z, $position, $whence);
  1328.  
  1329.  
  1330.  
  1331.  
  1332. Provides a sub-set of the C<seek> functionality, with the restriction
  1333. that it is only legal to seek forward in the output file/buffer.
  1334. It is a fatal error to attempt to seek backward.
  1335.  
  1336. Empty parts of the file/buffer will have NULL (0x00) bytes written to them.
  1337.  
  1338.  
  1339.  
  1340. The C<$whence> parameter takes one the usual values, namely SEEK_SET,
  1341. SEEK_CUR or SEEK_END.
  1342.  
  1343. Returns 1 on success, 0 on failure.
  1344.  
  1345. =head2 binmode
  1346.  
  1347. Usage is
  1348.  
  1349.     $z->binmode
  1350.     binmode $z ;
  1351.  
  1352. This is a noop provided for completeness.
  1353.  
  1354. =head2 opened
  1355.  
  1356.     $z->opened()
  1357.  
  1358. Returns true if the object currently refers to a opened file/buffer. 
  1359.  
  1360. =head2 autoflush
  1361.  
  1362.     my $prev = $z->autoflush()
  1363.     my $prev = $z->autoflush(EXPR)
  1364.  
  1365. If the C<$z> object is associated with a file or a filehandle, this method
  1366. returns the current autoflush setting for the underlying filehandle. If
  1367. C<EXPR> is present, and is non-zero, it will enable flushing after every
  1368. write/print operation.
  1369.  
  1370. If C<$z> is associated with a buffer, this method has no effect and always
  1371. returns C<undef>.
  1372.  
  1373. B<Note> that the special variable C<$|> B<cannot> be used to set or
  1374. retrieve the autoflush setting.
  1375.  
  1376. =head2 input_line_number
  1377.  
  1378.     $z->input_line_number()
  1379.     $z->input_line_number(EXPR)
  1380.  
  1381.  
  1382. This method always returns C<undef> when compressing. 
  1383.  
  1384.  
  1385.  
  1386. =head2 fileno
  1387.  
  1388.     $z->fileno()
  1389.     fileno($z)
  1390.  
  1391. If the C<$z> object is associated with a file or a filehandle, this method
  1392. will return the underlying file descriptor.
  1393.  
  1394. If the C<$z> object is is associated with a buffer, this method will
  1395. return undef.
  1396.  
  1397. =head2 close
  1398.  
  1399.     $z->close() ;
  1400.     close $z ;
  1401.  
  1402.  
  1403.  
  1404. Flushes any pending compressed data and then closes the output file/buffer. 
  1405.  
  1406.  
  1407.  
  1408. For most versions of Perl this method will be automatically invoked if
  1409. the IO::Compress::Zip object is destroyed (either explicitly or by the
  1410. variable with the reference to the object going out of scope). The
  1411. exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
  1412. these cases, the C<close> method will be called automatically, but
  1413. not until global destruction of all live objects when the program is
  1414. terminating.
  1415.  
  1416. Therefore, if you want your scripts to be able to run on all versions
  1417. of Perl, you should call C<close> explicitly and not rely on automatic
  1418. closing.
  1419.  
  1420. Returns true on success, otherwise 0.
  1421.  
  1422. If the C<AutoClose> option has been enabled when the IO::Compress::Zip
  1423. object was created, and the object is associated with a file, the
  1424. underlying file will also be closed.
  1425.  
  1426.  
  1427.  
  1428.  
  1429. =head2 newStream([OPTS])
  1430.  
  1431. Usage is
  1432.  
  1433.     $z->newStream( [OPTS] )
  1434.  
  1435. Closes the current compressed data stream and starts a new one.
  1436.  
  1437. OPTS consists of any of the the options that are available when creating
  1438. the C<$z> object.
  1439.  
  1440. See the L</"Constructor Options"> section for more details.
  1441.  
  1442.  
  1443. =head2 deflateParams
  1444.  
  1445. Usage is
  1446.  
  1447.     $z->deflateParams
  1448.  
  1449. TODO
  1450.  
  1451.  
  1452. =head1 Importing 
  1453.  
  1454.  
  1455. A number of symbolic constants are required by some methods in 
  1456. C<IO::Compress::Zip>. None are imported by default.
  1457.  
  1458.  
  1459.  
  1460. =over 5
  1461.  
  1462. =item :all
  1463.  
  1464.  
  1465. Imports C<zip>, C<$ZipError> and all symbolic
  1466. constants that can be used by C<IO::Compress::Zip>. Same as doing this
  1467.  
  1468.     use IO::Compress::Zip qw(zip $ZipError :constants) ;
  1469.  
  1470. =item :constants
  1471.  
  1472. Import all symbolic constants. Same as doing this
  1473.  
  1474.  
  1475.     use IO::Compress::Zip qw(:flush :level :strategy :zip_method) ;
  1476.  
  1477.  
  1478. =item :flush
  1479.  
  1480. These symbolic constants are used by the C<flush> method.
  1481.  
  1482.     Z_NO_FLUSH
  1483.     Z_PARTIAL_FLUSH
  1484.     Z_SYNC_FLUSH
  1485.     Z_FULL_FLUSH
  1486.     Z_FINISH
  1487.     Z_BLOCK
  1488.  
  1489. =item :level
  1490.  
  1491. These symbolic constants are used by the C<Level> option in the constructor.
  1492.  
  1493.     Z_NO_COMPRESSION
  1494.     Z_BEST_SPEED
  1495.     Z_BEST_COMPRESSION
  1496.     Z_DEFAULT_COMPRESSION
  1497.  
  1498.  
  1499. =item :strategy
  1500.  
  1501. These symbolic constants are used by the C<Strategy> option in the constructor.
  1502.  
  1503.     Z_FILTERED
  1504.     Z_HUFFMAN_ONLY
  1505.     Z_RLE
  1506.     Z_FIXED
  1507.     Z_DEFAULT_STRATEGY
  1508.  
  1509.  
  1510. =item :zip_method
  1511.  
  1512. These symbolic constants are used by the C<Method> option in the
  1513. constructor.
  1514.  
  1515.     ZIP_CM_STORE
  1516.     ZIP_CM_DEFLATE
  1517.     ZIP_CM_BZIP2
  1518.  
  1519.     
  1520.     
  1521.  
  1522. =back
  1523.  
  1524. For 
  1525.  
  1526. =head1 EXAMPLES
  1527.  
  1528. TODO
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540. =head1 SEE ALSO
  1541.  
  1542. L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>, L<IO::Uncompress::AnyUncompress>
  1543.  
  1544. L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
  1545.  
  1546. L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
  1547. L<Archive::Tar|Archive::Tar>,
  1548. L<IO::Zlib|IO::Zlib>
  1549.  
  1550.  
  1551. For RFC 1950, 1951 and 1952 see 
  1552. F<http://www.faqs.org/rfcs/rfc1950.html>,
  1553. F<http://www.faqs.org/rfcs/rfc1951.html> and
  1554. F<http://www.faqs.org/rfcs/rfc1952.html>
  1555.  
  1556. The I<zlib> compression library was written by Jean-loup Gailly
  1557. F<gzip@prep.ai.mit.edu> and Mark Adler F<madler@alumni.caltech.edu>.
  1558.  
  1559. The primary site for the I<zlib> compression library is
  1560. F<http://www.zlib.org>.
  1561.  
  1562. The primary site for gzip is F<http://www.gzip.org>.
  1563.  
  1564.  
  1565.  
  1566.  
  1567. =head1 AUTHOR
  1568.  
  1569. This module was written by Paul Marquess, F<pmqs@cpan.org>. 
  1570.  
  1571.  
  1572.  
  1573. =head1 MODIFICATION HISTORY
  1574.  
  1575. See the Changes file.
  1576.  
  1577. =head1 COPYRIGHT AND LICENSE
  1578.  
  1579. Copyright (c) 2005-2007 Paul Marquess. All rights reserved.
  1580.  
  1581. This program is free software; you can redistribute it and/or
  1582. modify it under the same terms as Perl itself.
  1583.  
  1584.  
  1585.